{/* Copyright 2020 Adobe. All rights reserved.
This file is licensed to you under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. You may obtain a copy
of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
OF ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License. */}

import {Layout} from '@react-spectrum/docs';
export default Layout;

import docs from 'docs:@react-spectrum/breadcrumbs';
import {HeaderInfo, PropTable, TypeLink, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-spectrum/breadcrumbs/package.json';

```jsx import
import {Breadcrumbs, Item} from '@react-spectrum/breadcrumbs';
import {View} from '@react-spectrum/view';
```

---
category: Navigation
keywords: [collections, dropdown]
---

# Breadcrumbs

<PageDescription>{docs.exports.Breadcrumbs.description}</PageDescription>

<HeaderInfo
  packageData={packageData}
  componentNames={['Breadcrumbs', 'Item']}
  sourceData={[
    {type: 'Spectrum', url: 'https://spectrum.adobe.com/page/breadcrumbs/'}
  ]}
  since="3.0.0" />

## Example

```tsx example
<Breadcrumbs>
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
  <Item key="march 2020 assets">March 2020 Assets</Item>
</Breadcrumbs>
```

## Content
Breadcrumbs follow the [Collection Components](collections.html) API, accepting only static children.
Similar to [Menu](Menu.html), Breadcrumbs accepts &lt;<TypeLink links={docs.links} type={docs.exports.Item} />&gt; elements as children,
each with a `key` prop, which is passed to the `onAction` handler to identify the selected item.
Basic usage of Breadcrumbs, as seen in the example above, shows a list of <TypeLink links={docs.links} type={docs.exports.Item} /> elements,
populated with a string. See [Events](#events) for more information.

### Internationalization
In order to internationalize Breadcrumbs, the content of all child items should be localized.

## Events
Use the `onAction` prop as a callback to handle press events on items.

```tsx example
function Example() {
  let folders = [
    {id: 1, label: 'Home'},
    {id: 2, label: 'Trendy'},
    {id: 3, label: 'March 2020 Assets'}
  ];
  let [folderId, setFolderId] = React.useState(null);
  return (
    <div>
      <Breadcrumbs onAction={(a) => setFolderId(a)}>
        {folders.map(f => <Item key={f.id}>{f.label}</Item>)}
      </Breadcrumbs>
      <p>You pressed folder ID: {folderId}</p>
    </div>
  );
}
```

## Links

By default, interacting with an item in Breadcrumbs triggers `onAction`. Items may also be links to another page or website. This can be achieved by passing the `href` prop to the `<Item>` component.

```tsx example
<Breadcrumbs>
  <Item href="#">Home</Item>
  <Item href="#">React Spectrum</Item>
  <Item>Breadcrumbs</Item>
</Breadcrumbs>
```

### Client side routing

The `<Item>` component works with frameworks and client side routers like [Next.js](https://nextjs.org/) and [React Router](https://reactrouter.com/en/main). As with other React Spectrum components that support links, this works via the [Provider](Provider.html) component at the root of your app. See the [client side routing guide](routing.html) to learn how to set this up.

## Props

<PropTable component={docs.exports.Breadcrumbs} links={docs.links} />

## Visual options

### Size
[View guidelines](https://spectrum.adobe.com/page/breadcrumbs/#Options)

Small
```tsx example
<Breadcrumbs size="S">
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
</Breadcrumbs>
```

Medium
```tsx example
<Breadcrumbs size="M">
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
</Breadcrumbs>
```

Large (default)
```tsx example
<Breadcrumbs size="L">
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
</Breadcrumbs>
```

### Multiline

Use the `isMultiline` prop to place the last item below the other items.
This adds emphasis to the current location as a page title or heading.

```tsx example
<Breadcrumbs isMultiline>
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
  <Item key="march 2020 assets">March 2020 Assets</Item>
</Breadcrumbs>
```

### Root context
[View guidelines](https://spectrum.adobe.com/page/breadcrumbs/#With-root-context)

Some applications find that always displaying the root item is useful to orient users.
This variation keeps the root visible when other items are truncated into the menu.

```tsx example
<View overflow="hidden" width="200px">
  <Breadcrumbs showRoot>
    <Item key="home">Home</Item>
    <Item key="trendy">Trendy</Item>
    <Item key="2020 assets">March 2020 Assets</Item>
    <Item key="winter">Winter</Item>
    <Item key="holiday">Holiday</Item>
  </Breadcrumbs>
</View>
```

### Disabled

Breadcrumbs in a disabled state shows items, but indicates that navigation is not available.
This can be used to maintain layout continuity.

```tsx example
<Breadcrumbs isDisabled>
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
  <Item key="march 2020 assets">March 2020 Assets</Item>
</Breadcrumbs>
```

### Visible items (overflow behavior)
[View guidelines](https://spectrum.adobe.com/page/breadcrumbs/#Truncation-and-overflow)

Breadcrumbs collapses items into a menu when space is limited. It will only show a maximum of 4 visible items including the root and menu button, if either are visible. If the root item cannot be rendered in the available horizontal
space, it will be collapsed into the menu regardless of `showRoot`. Note that the last breadcrumb item will automatically
truncate with an ellipsis instead of collapsing into the menu.

Resize your browser window to see the above behavior in the examples below.

```tsx example
<Breadcrumbs>
  <Item key="shared">My Shared Documents</Item>
  <Item key="catalogue">North America Spring Catalogue</Item>
  <Item key="march 2020">March 2020</Item>
  <Item key="assets">Downloaded Screenshots and Assets (approval required)</Item>
  <Item key="streetwear">Streetwear</Item>
  <Item key="jackets">Jackets</Item>
</Breadcrumbs>
```

```tsx example
<Breadcrumbs showRoot>
  <Item key="shared">My Shared Documents</Item>
  <Item key="catalogue">North America Spring Catalogue</Item>
  <Item key="march 2020">March 2020</Item>
  <Item key="assets">Downloaded Screenshots and Assets (approval required)</Item>
</Breadcrumbs>
```
